home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / mp_basic.pro < prev    next >
Text File  |  1997-07-08  |  10KB  |  304 lines
  1. ; $Id: mp_basic.pro,v 1.9 1997/01/15 03:11:50 ali Exp $
  2. ;
  3. ; Copyright (c) 1988-1997, Research Systems, Inc.  All rights reserved.
  4. ;       Unauthorized reproduction prohibited.
  5.  
  6. ;+
  7. ; NAME:
  8. ;    MP_BASIC
  9. ;
  10. ; PURPOSE:
  11. ;    Provide online documentation for IDL topics. The style
  12. ;    is a cross between Unix man pages and VMS online help.  The
  13. ;    help is organized in a two level hierarchy --- Level 1 is the
  14. ;    global subject, and Level 2 supplies help on subjects within
  15. ;    each global subject.  If !D.WINDOW is not -1, (window system in use)
  16. ;    the mouse is used to prompt for subjects, otherwise, the normal tty
  17. ;    interface is used.
  18. ;
  19. ;    THIS ROUTINE IS TO BE CALLED ONLY BY MAN_PROC.  Users can obtain
  20. ;    online help by using the "?" command.
  21. ;
  22. ; CATEGORY:
  23. ;    Help, documentation.
  24. ;
  25. ; CALLING SEQUENCE:
  26. ;    MP_BASIC [, Request]
  27. ;
  28. ; INPUTS:
  29. ;     REQUEST:    A scalar string containing the item on which help is desired.
  30. ;        This string can contain 1 or 2 (whitespace separated) words.
  31. ;        The first word is taken as the global topic and the second
  32. ;        as the topic within the scope of the first.  The procedure
  33. ;        prompts for missing words.
  34. ;
  35. ; OUTPUTS:
  36. ;    Help text is sent to the standard output.
  37. ;
  38. ; COMMON BLOCKS:
  39. ;    None.
  40. ;
  41. ; RESTRICTIONS:
  42. ;    The help text is derived from the LaTeX files used to produce
  43. ;    the reference manual.  However, it is not possible to produce
  44. ;    exactly the same output as found in the manual due to limitations
  45. ;    of text oriented terminals.  The text used is therefore considerably
  46. ;    abbreviated.  Always check the manual if the online help is
  47. ;    insufficient.
  48. ;
  49. ; MODIFICATION HISTORY:
  50. ;    3 November 1988, AB
  51. ;
  52. ;    January, 1989, AB
  53. ;    Added ambiguity resolution, ability to handle multiple levels,
  54. ;    and support for mouse.
  55. ;
  56. ;       SNG, December, 1990    Added support for MS-DOS.
  57. ;
  58. ;    3 January 1991, AB
  59. ;    Renamed from MAN_PROC to make room for the widget version.
  60. ;    
  61. ;       Bobby Candey, Atlantic Research         30 January 1991
  62. ;       Added looping in VMS version to extract multiple "]" from filenames
  63. ;
  64. ;       31 December 1992, AB    Modified to ignore the optional %TITLE
  65. ;                               line at the top of the file. There's no
  66. ;                               reason to handle it, since this routine is
  67. ;                               obsolete. The builtin online help system
  68. ;                               *does* handle it.
  69. ;
  70. ;    11 February 1993, SMR    Added support for the Mac Version
  71. ;    21 April 1993, AB, Added ability to use new !HELP_PATH system
  72. ;        variable to locate help files.
  73. ;    13 January 1994, AB    Added ability to understand new version
  74. ;                2 help files with extended identifier names.
  75. ;
  76. ;-
  77. ;
  78.  
  79. function MPB_SELTOPIC, SUBJECT, TOPIC_ARRAY, INITIAL
  80. ; Given a subject header and an array of topics, returns a string with
  81. ; the requested topic (which may or may not be in TOPIC_ARRAY).
  82. ; Initial is the index of the initial selection to be highlighed *if*
  83. ; a window system menu is used.
  84. on_error,2                      ;Return to caller if an error occurs
  85. target = ''
  86. if((!d.name eq 'X') or (!d.name eq 'SUN')) then begin
  87.     index = wmenu([SUBJECT, TOPIC_ARRAY], title=0, initial=initial)
  88.     if (index ne -1) then target = TOPIC_ARRAY[index-1]
  89.   endif else begin                ; Use tty
  90.     if (!VERSION.OS NE 'MacOS') then $
  91.       openw, outunit, filepath(/TERMINAL), /MORE, /GET_LUN $
  92.     else outunit = -1
  93.     printf, outunit, format = '(/,A,":",/)', SUBJECT
  94.     printf, outunit, TOPIC_ARRAY
  95.     if (!VERSION.OS NE 'MacOS') then close, outunit
  96.     outunit = 0
  97.     print, format='(/,/)'
  98.     read, 'Enter topic for which help is desired: ', target
  99.   endelse
  100.  
  101. return, STRCOMPRESS(STRUPCASE(target),/REMOVE_ALL)    ; Up case & no blanks
  102. end
  103.  
  104.  
  105.  
  106. function MPB_TM, KEY, TOPIC_ARRAY, FOUND, OUTUNIT
  107. ; Topic MAtch. Given a string, MPB_TM returns an array of indicies into
  108. ; TOPIC_ARRAY that match into FOUND. If there is an exact match
  109. ; only its index is returned, otherwise all elements with the same prefix
  110. ; match. The number of elements that matched is returned.
  111. ; OUTUNIT is the file unit to which output should be directed.
  112. on_error,2                      ;Return to caller if an error occurs
  113. l_topic_array = strupcase(topic_array)
  114. found = [ where(STRTRIM(L_TOPIC_ARRAY) eq KEY, count) ] ; Match exact string
  115. if (count le 0) then begin    ; No exact match, try to match the prefix
  116.   FOUND = [ where(strpos(L_TOPIC_ARRAY, KEY) eq 0, count) ]
  117.   if ((count le 0) or (KEY eq '')) then begin        ;Found it?
  118.     count = 0
  119.     printf,outunit, !MSG_PREFIX, 'Nothing matching topic "',KEY,'" found."'
  120.     printf,outunit, !MSG_PREFIX, 'Enter "?" for list of available topics.'
  121.   endif else begin
  122.     if (count ne 1) then begin
  123.       printf, outunit, format = "(A,'Ambiguous topic ""', A, '"" matches:')",$
  124.          !MSG_PREFIX, KEY
  125.       printf, OUTUNIT, TOPIC_ARRAY[FOUND]
  126.       endif
  127.   endelse
  128. endif
  129. return, count
  130. end
  131.  
  132.  
  133.  
  134. PRO MP_BASIC, REQUEST
  135.  
  136.   on_error,1                      ; Return to main level if error occurs
  137.   outunit = (inunit = 0)
  138.   lv1_topic = (lv2_topic = '')
  139.  
  140.   if (N_ELEMENTS(REQUEST)) then begin
  141.     temp = size(request)
  142.     if (temp[0] NE 0) then begin
  143.       MSG = 'Argument must be scalar.'
  144.       goto, fatal
  145.       endif
  146.     if (temp[1] NE 7) then begin
  147.       MSG = 'Argument must be of type string.'
  148.       goto, FATAL
  149.       endif
  150.     ; Parse into 1 or two strings
  151.     lv1_topic = STRUPCASE(STRTRIM(STRCOMPRESS(REQUEST), 2))
  152.     if (((blank_pos = STRPOS(lv1_topic, ' '))) ne -1) then begin
  153.     lv2_topic = STRMID(lv1_topic, blank_pos+1, 10000L)
  154.     lv1_topic = STRMID(lv1_topic, 0, blank_pos)
  155.       endif
  156.   endif
  157.  
  158.  
  159.   ; lv1_files recieves all help files found through !HELP_PATH.
  160.   lv1_dirs = EXPAND_PATH(!HELP_PATH, /ARRAY, COUNT=cnt)
  161.   if (cnt eq 0) then begin
  162.     MSG = 'No online help files found.'
  163.     goto, fatal
  164.   endif
  165.   for i = 0, cnt-1 do begin
  166.     tmp = STRLOWCASE(findfile(filepath('*.help', root_dir=lv1_dirs[i])))
  167.     if (i eq 0) then lv1_files = TEMPORARY(tmp) $
  168.     else lv1_files=[lv1_files, TEMPORARY(tmp)]
  169.   endfor
  170.  
  171.   ; lv1_topics gets uppercase version of just the names.
  172.   lv1_topics = STRUPCASE(lv1_files)
  173.   if !version.os ne 'Win32' then begin
  174.     tail = STRPOS(lv1_topics, '.HELP')
  175.   endif else begin
  176.     tail = STRPOS(lv1_topics, '.HEL')
  177.   endelse
  178.   n = n_elements(lv1_topics)
  179.   for i = 0, n-1 do $
  180.     lv1_topics[i] = strmid(lv1_topics[i], 0, tail[i])
  181.   for i = 0, n-1 do begin    ; Strip path part off lv1_topics
  182.     case !version.os of
  183.       'vms': begin
  184.            j = STRPOS(lv1_topics[i], ']')
  185.            while (j ne -1) do begin
  186.              lv1_topics[i] = strmid(lv1_topics[i], j+1, 32767)
  187.              j = STRPOS(lv1_topics[i], ']')
  188.            endwhile
  189.       end
  190.       'Win32': begin
  191.         j = STRPOS(lv1_topics[i], '\')
  192.         while (j ne -1) do begin
  193.         lv1_topics[i] = strmid(lv1_topics[i], j+1, 32767)
  194.           j = STRPOS(lv1_topics[i], '\')
  195.         endwhile
  196.       end
  197.       'MacOS': begin
  198.         j = STRPOS(lv1_topics[i], ':')
  199.         while (j ne -1) do begin
  200.         lv1_topics[i] = strmid(lv1_topics[i], j+1, 32767)
  201.           j = STRPOS(lv1_topics[i], ':')
  202.         endwhile
  203.       end
  204.       else:  begin      ; Unix otherwise
  205.         j = STRPOS(lv1_topics[i], '/')
  206.         while (j ne -1) do begin
  207.         lv1_topics[i] = strmid(lv1_topics[i], j+1, 32767)
  208.           j = STRPOS(lv1_topics[i], '/')
  209.         endwhile
  210.       end
  211.     endcase
  212.   endfor
  213.  
  214.   ; Sort the topics into alphabetical order.
  215.   tmp = sort(lv1_topics)
  216.   lv1_files = lv1_files[tmp]
  217.   lv1_topics = lv1_topics[tmp]
  218.  
  219.   initial = where(lv1_topics eq 'ROUTINES')
  220.   if (lv1_topic eq '') then $
  221.     lv1_topic = MPB_SELTOPIC('Help categories', lv1_topics, initial[0]+1)
  222.   if (!VERSION.OS NE 'MacOS') then $
  223.     openw, outunit, filepath(/TERMINAL), /MORE, /GET_LUN $
  224.   else outunit = -1
  225.   if (((count=MPB_TM(lv1_topic,lv1_topics,found,outunit))) eq 0) then $
  226.     goto, done
  227.   IF (!VERSION.OS NE 'MacOS') THEN free_lun, outunit
  228.   outunit = 0
  229.   lv2_subject = lv1_topics[found[0]]        ; Use the first element
  230.  
  231.   ; At this point, a global subject exists, process the specific subject
  232.   lv2_topics = ''
  233.   offset = 0L
  234.   openr, inunit, lv1_files[found[0]], /GET_LUN
  235.   outunit = 0;
  236.   n = 0L
  237.   tmp=''
  238.   readf,inunit,tmp                ; Read first line.
  239.   ; If it's the version tag, parse it.
  240.   version = 1L                    ; Assume old format
  241.   if (strmid(tmp, 0, 9) eq '%VERSION:') then begin
  242.     reads, tmp, version, format='(9X, I0)'
  243.     readf,inunit,tmp                ; Read next line.
  244.   endif
  245.   if (strmid(tmp, 0, 7) eq '%TITLE:') then readf, inunit, tmp   ; Skip title
  246.   n = long(tmp)                    ;# of records
  247.   if (version ne 1) then begin
  248.     ; Version 2 format has the number of characters used by all the
  249.     ; subtopics on the next line. We don't use it, but have to read it
  250.     readf,inunit,tmp                ; Read next line.
  251.   endif
  252.   lv2_topics = strarr(n)            ;Make names
  253.   readf,inunit,lv2_topics            ;Read entire string to inunit
  254.   if (version eq 1) then begin
  255.     offsets = long(strmid(lv2_topics, 15, 30))    ;Extract starting bytes
  256.     lv2_topics = strmid(lv2_topics,0,15)        ;Isolate names
  257.   endif else begin
  258.     offsets = lonarr(n)
  259.     for i = 0, n-1 do begin
  260.       tmp = lv2_topics[i]
  261.       colon = strpos(tmp, ':') + 1        ; Find delimiter
  262.       offsets[i] = long(strmid(tmp, 0, colon))
  263.       lv2_topics[i] = strmid(tmp, colon, 10000000)
  264.     endfor
  265.   endelse
  266.  
  267.   ; Determine the base of the help text
  268.   tmp = fstat(inunit)
  269.   text_base = tmp.cur_ptr
  270.  
  271.   ; If no topic is supplied, prompt for one
  272.   if lv2_topic eq '' then $
  273.     lv2_topic = MPB_SELTOPIC(STRUPCASE(lv2_subject), lv2_topics, 1)
  274.  
  275.   if (!VERSION.OS NE 'MacOS') THEN $
  276.     openw, outunit, filepath(/TERMINAL), /MORE, /GET_LUN $
  277.   else outunit = -1
  278.   if (((count=MPB_TM(lv2_topic,lv2_topics,found,outunit))) eq 0) then $
  279.     goto, done
  280.   str = ''
  281.   for i = 0, count-1 do begin
  282.     index = found[i]
  283.     if (count ne 1) then $
  284.       printf, outunit, lv2_topics[index], $
  285.           format='("***************",/,A,/,"***************")'
  286.       POINT_LUN, inunit, text_base + offsets[index]
  287.       readf, inunit, str        ; Skip the ";+"
  288.       readf, inunit, str
  289.       !err = 0
  290.       while (str NE ";-") do begin
  291.     printf, outunit, str, ' '
  292.     if !err ne 0 then goto, DONE
  293.     readf, inunit, str
  294.     endwhile
  295.       endfor
  296.  
  297.   goto, DONE
  298. FATAL:        ; The string MSG must be set
  299.   message, MSG, /RETURN
  300. DONE:
  301.   if (outunit ne 0) then FREE_LUN, outunit
  302.   if (inunit ne 0) then FREE_LUN, inunit
  303. end
  304.